﻿namespace Sage.CloudStorage.Qiniu.Events
{
    /// <summary>
    /// 上传完成事件参数
    /// 包含上传任务完成后的详细信息，支持成功和失败两种状态
    /// </summary>
    /// <remarks>
    /// **事件用途**：
    /// - **完成通知**：通知上传任务的最终状态
    /// - **结果处理**：提供成功或失败的详细信息
    /// - **统计收集**：收集上传性能和成功率数据
    /// - **错误处理**：提供详细的错误信息用于问题诊断
    /// - **日志记录**：记录上传任务的完整信息
    /// 
    /// **应用场景**：
    /// - **用户界面**：显示上传结果给用户
    /// - **业务逻辑**：根据上传结果执行后续业务操作
    /// - **监控告警**：上传失败时触发告警机制
    /// - **数据统计**：统计上传成功率和性能指标
    /// - **调试分析**：分析上传失败的原因
    /// </remarks>
    public class UploadCompletedEventArgs : EventArgs
    {
        /// <summary>
        /// 是否上传成功
        /// true表示上传成功，false表示上传失败
        /// </summary>
        public bool IsSuccess { get; set; }

        /// <summary>
        /// 上传的文件键名
        /// 文件在七牛云存储中的完整路径标识
        /// </summary>
        /// <remarks>
        /// 键名格式示例：
        /// - "documents/report.pdf" - 文档类文件
        /// - "images/2024/03/photo.jpg" - 按日期组织的图片
        /// - "users/123/avatar.png" - 用户相关文件
        /// - "temp/upload_20240315.zip" - 临时文件
        /// </remarks>
        public string Key { get; set; } = "";

        /// <summary>
        /// 文件哈希值（ETag）
        /// 七牛云返回的文件哈希值，用于验证文件完整性
        /// </summary>
        /// <remarks>
        /// Hash特点：
        /// - 由七牛云计算生成，确保唯一性
        /// - 可用于文件完整性验证
        /// - 相同内容的文件具有相同的Hash值
        /// - 可用作文件去重的依据
        /// - 格式通常为Base64编码的字符串
        /// 
        /// 用途：
        /// - 验证上传文件的完整性
        /// - 实现文件去重功能
        /// - 作为文件的唯一标识
        /// - 用于缓存控制（ETag头）
        /// </remarks>
        public string Hash { get; set; } = "";

        /// <summary>
        /// 文件大小（字节）
        /// 实际上传的文件大小，用于统计和验证
        /// </summary>
        public long FileSize { get; set; }

        /// <summary>
        /// 上传耗时
        /// 从开始上传到完成（或失败）的总耗时
        /// </summary>
        /// <remarks>
        /// 耗时统计：
        /// - 包括网络传输时间
        /// - 包括文件处理时间
        /// - 包括服务端响应时间
        /// - 不包括客户端文件读取预处理时间
        /// 
        /// 用途：
        /// - 性能监控和优化
        /// - 网络状况评估
        /// - 用户体验改进
        /// - 系统负载分析
        /// </remarks>
        public TimeSpan Duration { get; set; }

        /// <summary>
        /// 错误信息（失败时）
        /// 当IsSuccess为false时，包含失败的详细错误描述
        /// </summary>
        /// <remarks>
        /// 错误信息来源：
        /// - 网络连接错误
        /// - 七牛云服务返回的错误
        /// - 文件读取错误
        /// - 认证失败错误
        /// - 策略配置错误
        /// 
        /// 常见错误类型：
        /// - "文件不存在" - 本地文件不存在或无法访问
        /// - "网络连接超时" - 网络连接问题
        /// - "认证失败" - AccessKey或SecretKey错误
        /// - "存储桶不存在" - 指定的bucket不存在
        /// - "文件过大" - 超过上传策略的大小限制
        /// - "类型不支持" - 文件类型不符合策略限制
        /// </remarks>
        public string? ErrorMessage { get; set; }

        /// <summary>
        /// 异常对象（失败时）
        /// 当IsSuccess为false时，包含导致失败的原始异常对象
        /// </summary>
        /// <remarks>
        /// 异常用途：
        /// - 详细的技术错误信息
        /// - 异常堆栈跟踪
        /// - 用于开发调试
        /// - 错误分类和统计
        /// 
        /// 常见异常类型：
        /// - HttpRequestException：网络请求异常
        /// - FileNotFoundException：文件不存在异常
        /// - UnauthorizedAccessException：认证失败异常
        /// - TimeoutException：请求超时异常
        /// - ArgumentException：参数错误异常
        /// </remarks>
        public Exception? Exception { get; set; }
    }
}
